REST, GRPC эндпоинты, Swagger

• Сервисы можно и нужно регистрировать в методе регистрации сервисов
• Чтобы сделать контроллер, нужно отнаследовать его либо от Controller либо от BaseController. Base содержит минимальную реализацию в отличии от Controller
• Возвращать можно:
  • IActionResult - только код
  • Объекты напрямую
  • ActionResult
  Лучше следовать одному подходу в контроллере
• По DTO верхний слой может знать что то о нижнем, но не наоборот. Таким образом, парсить к классу траспортного уровня из Request, должен контроллер, а не сервис
• Когда полностью по REST урлы выглядят так:
  1. api/companies/124/employes/5432/issues/12
• Когда сделано как делаю обычно я, то есть в урлах прям глаголы api/issues/modify-issue
  Этот подход называется RPC-like
  
• В случае если появляются например какие то изменения в модели реквеста, то следует делать версионирование API, прям заводить контроллер v2 и далее работаь с ним, а также оповесстить пользователей чтобы они переезжали на новую версию
• Чтобы заработал контроллер его нужно добавить в DI через AddController, а также добавить в useEndpoints
• Также очень хорошо выносить например сервисы в отдельные нугетпакеты. Для генерации нугетпакетов использовать директивую в csproj

<GeneratePackageOnBuild>true</GeneratePackageOnBuild> 
<Version>1.0.0</Version>
Copy

• Для управлением того что будет рисовать Swagger применяется атрибут:

[ProducesResponseType({Type}, {code})]
Copy

А также применяется возвращаемый тип

IActionResult - чтобы ничего не рисовалось в качестве типа

IActionResult<{Type}> - чтобы рисовался тип

Code может быть как цифрой так и int константой StatusCodes.Status200Ok

• Swagger вовремя генерации смотрит только на название класса, поэтому если будет другой класс с таким же именем возвращаться из метода, то вылетит ошибка и сваггер не соберется.
  Решение:
  

services.AddSwaggerGen(c => {
		// ....
		// Some code
		c.CustomShemaIds(s => s.FullName);
});
Copy

• Для того чтобы xml коментарии генерировались в swagger тоже - требуется:

Добавить в .csproj

<GenerateDocumentationFile>true</GenerateDocumentationFile>
Copy

А также добавить в конфигурацию swagger:

services.AddSwaggerGen(c => {
		// ....
		// Some code
		var xmlPath = Path.Combine(AppContext.BaseDirectory,
								 $"{Assembly.GetExecutingAssembly().GetName()}.xml}");
		c.IncludeXmlComments(xmlPath);
});
Copy

• Middleware это конвеер, порядок запуска которого определяется в методе Configure класса Startup. Один из парметров метода IApplicationBuilder app. В нем есть методы:
  1. Use() добавляет новый элмент в конвеер. Конвеер может как закончиться н аэтом методе и пойти вверх, так и пойти дальше
  2. Run() метод на котором заканчивается работа конвеера.
  3. Map() метод который позволяет разветвлять логику работы конвеера в зависимоти от адреса запроса.
  4. UseMiddleware().
  Для создания класса Middleware требуется чтобы класс реализовывал конструктор, который принимает аргумент RequestDelegate next, для вызова следующего middleware, а также реализует метод InvokeAsync(HttpContext) Хороший тон добавлять собственные MiddleWare с помощью расширений.
  Пример:

  public static class LogUrlMiddlewareExtentions
  {
  	public static IApplicationBuilder UseLogUrl(this IApplicationBuilder app)
  	{
  		return app.UseMiddleware<LogUrlMiddleware>();
  	}
  }
  Copy

…